perm filename USERGD.PN[UP,DOC] blob
sn#690388 filedate 1982-12-07 generic text, type C, neo UTF8
COMMENT ⊗ VALID 00010 PAGES
C REC PAGE DESCRIPTION
C00001 00001
C00002 00002 General notes
C00005 00003 Execution Profiles
C00007 00004 Fortran Compile-time Options
C00009 00005 Pascal and Pascal* compile-time options
C00012 00006 Optimizer options: PMERGE (procedure merger)
C00016 00007 Optimizer options: UOPT (global optimizer)
C00017 00008 Ugen Code Generator Options
C00021 00009 Extensions to Pascal and other Things to Know about Upas
C00051 00010 Running the system at SAIL and S1-A using PAS
C00058 ENDMK
C⊗;
General notes
This document is designed to help users of the Stanford
Pascal*/Fortran system for the Dec-10 and the S-1 Mark IIa on S1-A. It
starts off with a guide to the compile-time options and non-standard/
implementation-dependent features of the Fortran and Pascal compilers. It
then gives some details of running the system using PAS.
(For the S-1 Mark I, see USERGD.1[S,DOC] (by typing "READ USERGD.1").
(For Version-changer documentation, READ VERCH).
B-code (binary U-code) is now always used. If you want to look at
the U-code, use the PAS switches /UCO/E, which will invoke the B-code to
U-code translator, and then put you in the editor.
The source-level debugger and the execution profiler (which tells you
both how many times each statement was executed and how much time was
spent in each procedure) work for both Pascal and Fortran (Dec-10 only.)
See section on profiling.
The Fortran compiler should work except for double precision, and
pointer address arithmetic.
Execution Profiles
There are two kinds of profiles available. Statement counts record
how many times each source statement was executed. Procedure timings
record the time spent in each procedure, both in the procedure alone, and
in the procedure and all its descendents. (Because this involves two
calls to the clock per procedure call, this typically triples the
execution time of the program on the Foonly.)
To get an execution profile of your program, use the option (*#P n*)
in a Pascal program, or give the option TPROFILE n to Ufort or Ugen.
Values of n are 1 for statement counts, 2 for procedure timings, and 3 for
both. After the program has finished executing, it will put you in the
profiler, which allows you to get either complete or selected listings
(type HELP when you get there). Currently, profiling must be turned on
for all modules in the program in order to work.
Fortran Compile-time Options
...are set by a SET statement of the form
"SET" <option setting> {","<option setting>}
<option setting> :=: <option name> "=" <T,F,or integer>
e.g.,
SET DBUG T,BCHK F
or they may may be given in the command line, e.g.,
R P10;TRIAL1.FOR\DBUG+
(see section on running programs).
Options that begin with a "T" are passed through to the code generator
(but most code generator options are not of interest to users). Options
that begin with a "Z" are passed through to the optimizer.
Name Initial value Meaning
BCHK F enable runtime array subscript checking
DBUG F emit code for use with debugger
WARN F emit warnings for non-fatal errors and
variables not set/used
BOUT F emit binary U-code (S1-a only)
LIST F emit complete listing
LOG F emit listing with only errors
TPROFILE 0 keep execution profile:
1 = statement counts
2 = procedure timings
3 = both
For documentation on the non-standard features, see the Ufort document
in the S-1 '79 report and {S1-A}FORUPD.DOC[S,DOC] and {S1-A}FORNEW.DOC[DOC,PN].
Pascal and Pascal* compile-time options
Options are given in a comment that begins with "(*#" (NOT "(*$"!).
or they may may be given in the command line (see section on running
programs). Options that begin with a "T" are passed through to the code
generator (but most code generator options are not of interest to users).
Options that begin with a "Z" are passed through to the optimizer.
Sample option line: (*#g+,b-*)
In the listing below, the options in parentheses are used for
debugging the system; they are probably not of interest to users.
Switch Meaning Default Value
------ ------- ------- -----
B+ Bounds and nil pointer checking +
(C+) Print ucode +
D+ Load with debugger -
(E+) Emit source code +
G+ Write errors only to listing file +
L+ Write full listing -
In Number of characters of identifiers that 16
are considered significant
O+ Emit optimizer-compatible code -
Pn Keep execution profile +
1 = statement counts
2 = procedure timings
3 = both
(Rn) Put up to N local variables in registers
S+ Accept standard Pascal only -
U- Leave procedure names exactly as is +
Wn PRINT WARNINGS FOR: 0
1 ununsed variables, types, procs, etc.
10 nested comments
Optimizer options: PMERGE (procedure merger)
ZMRG Merger control
0 - No merging is allowed in this module.
1 - Merging is allowed. [default]
ZMOD Module control
0 - The module is an actual module, leave
Block 2 procedures intact, merge all
others.
1 - The module is a final program. (default)
ZDEC Decision Algorithm control
0 - Do not merge unless explicitly told to.
1 - Merge procedures which are called once.
2 - Everything. Try to linearlize the program
3 - decide only on size of callee, decide
on a procedure by procedure basis.
[default]
4 - decision based both on size of callee
and loop nesting depth of call. Decide
on a call-by-call basis.
ZPRO Procedure decision control
0 - Do not merge any calls to the following
or current procedure.
1 - PMerge decides whether to merge or not.
[default].
2 - Merge ALL calls to this procedure. Over-
rides ZDEC above.
?? - decision factor to use?
ZCAL Call decision control
0 - Do NOT merge the next call. Does not
apply to nested calls.
1 - Use current decision algorithm. (default)
2 - Merge the next call.
ZFAC Merging decision factor.
n - Use the weight factor "n" in merging
decisions. The default n is 1000.
The smallest value of n is used.
Conflicts:
With all these options several conflicts can arise. For instance
marking a procedure unmergeable, then requiring that a call to
it be merged. Conflicts are resolved in favor of NOT merging.
Errors or warnings are reported as appropiate whenever a conflict
is detected.
Optimizer options: UOPT (global optimizer)
(Not yet available.)
Ugen Code Generator Options
Options for Ugen are usually used to pass information from the front
end, through the use of OPTN U-code statements. Some options have string
arguments which are passed in the comment following the OPTN statement.
Most options may also be given directly to Ugen through the command line.
Mark IIa only:
TFASTCHECK 1: Use bounds checking instructions,
instead of test-and-branch to error routine.
Dec-10 only:
TLOAD 1: Emit load request for the load file whose name follows
(may be used by user only in Pascal source: (*#TLOAD 'FOO.REL'.*)
TCORE N: Allocate N words of core; you can also change this by using
the REENTER command after the program has been loaded
TRTIMES N: For Dec-10, emit runtime load request:
1: Pascal runtimes -- calleesave
2: Fortran runtimes
3: Debugger
4: Pascal* runtimes
5: Profiler
6: Pascal runtimes
7: Pascal runtimes -- regparm
Most of the rest will not be of interest to users.
TDEBUG 1: Emit debugger info. For Dec-10, emit debugger load request
TERROR 1: The original source file had errors. Abort.
TMACHINE N: Machine id. Make sure is the same as own machine id.
TPROFILE 1: Emit code for execution profile. For Dec-10, emit profiler
load request.
TSOURCE 1: Source name follows.
TTYPES N: Reserve N locations in type table for debugger.
TSYM 1: Symbol table name follows.
TTRACE N:
1 = Print ucode instructions in assembly file
2 = Print instructions as they are emitted on first pass
4 = Trace ADJ,CHK of stets
8 = Trace register binding use
16 = Trace temporaries use
32 = Print Ucode statistics
64 = Print source file statements in assembly file
Extensions to Pascal and other Things to Know about Upas
Send all questions, comments, etc. to PN at SAIL. For Pascal*, see
PASCAL.MSS[DOC,PN]. (Ask PN for a hard copy.)
It is my opinion that Upas conforms to the Pascal Standard as it
appears in STAND.TXT[DOC,S1], with the exceptions noted on this page. I
would appreciate any evidence to the contrary. As well as extensions and
implementation-dependencies, this page notes standard features which are
often not implemented.
Anything with *** next to it is not yet implemented.
1. SEPARATE COMPILATION
Procedures may be separately compiled through the use of modules. All
modules besides the main module should start with MODULE <name> instead of
PROGRAM <name>. The main block, 'BEGIN S END.', is replaced with simply a
period. [This is different from Hedrick Pascal, where the semicolon
preceding the main block is also deleted.]
The module name is used to create a unique name for every procedure
that is not at the outer level, so as to lessen the chance of name
conflicts between modules. Because of this, each module name must differ
from other module names in the first N characters. (On the Dec-10, due to
loader limitation, N = 3.) Note that the U option may be use to force
Upas to either Uniquefy or to not Uniquefy a procedure name.
To use a procedure in another module, declare it EXTERN or EXTERNAL
(same syntax as FORWARD).
Each module may have its own global variables, which may not be shared
with other modules.
INCLUDE Files may be used, using the INCLUDE statement (e.g.,
"INCLUDE 'GLOBALS.INC';". All INCLUDE statements must appear before any
variable declarations, and can contain CONSTs, TYPEs, and external procedure
declarations. Only one level is allowed, i.e., an INCLUDE file may not
contain any INCLUDE statments.
CONST, TYPE, and external procedure declarations may appear in any order.
2. FILES and I/O
Files may be declared as local variables in a procedure or function,
or as array elements or record fields. If they are either of the latter,
they must be explicitly closed by the user using the Close procedure if he
wants them closed before the end of the program. Files that are declared
as local files are closed on normal procedure exit. (*** Not yet
implemented; use Close).
2.1 Input, Output, and the Program header
There are three implementation-defined files, called standard input,
standard output, and system output. They are usually mapped to the
terminal in interactive systems. If Input or Output occur in the program
header, then they are mapped to standard input and standard output.
Otherwise, program parameters have no effect on the program. The
predefined file SysOut, which is used for writing system output, such as
error messages, is always open to system output.
Put another way, if you want to write to the terminal, put Output in
your program header and write to Output. If you want Output to be a file,
don't put it in the program header, and it will be opened in the usual
way.
2.2 Reset, Rewrite, and Revise
Reset and Rewrite can be used as in standard Pascal, and will satisfy
the definition given in the standard. Revise is used for opening files
for both reading and writing. Normally, the user is prompted for the name
of a file, and if she types just a carriage return, the internal name
of the file is used, i.e., it will create a file 'F' for the call
'Rewrite(F)'. However, all three procedures hav two optional
string parameters that may be used to give the name of the file, and a
series of file opening commands, of the form
<identifer> [':"' <string> '"']
separated by semicolons. Example:
Reset (Input, 'DATA1.TXT','Nofilter;Prompt:"Try again -- "');
Standard commands are:
- Prompt: The string is used as a prompt (interactive
systems only). If a file name is NOT given, this
prompt is used to get the file name from the user. If
one IS given (like in the example above), the prompt is
used to get another file name from the user if the file
can't be opened.
- Default: The string is used are used as a default file
name, which is used if the user types a carriage return
in response to the prompt.
***- Temp: (Rewrite only.) This means that the file is to
be used for the life of the program only. A temporary
file name is generated, and the file disappears after
the program terminates, if it terminates normally.
- Standard: If Reset, the standard input file is used.
If Rewrite, the standard output is used.
- Nofilter: (Reset, Revise only.) Normally a text file
is 'filtered' by the runtimes so that it conforms to
the standard Pascal definition of a text file. Most
notably, any end-of-line characters are changed into
one space. The inclusion of Nofilter causes all
characters to be passed through exactly as they appear
in the text file. Eoln, Eopage and Readln still work
as for standard files.
2.3 Get, Eopage, and Interactive Files
For text files, the procedure Get bypasses nulls, and converts tabs to
the appropriate number of spaces to make it look like a tab. It converts
end-of-line characters and page markers to spaces. Other
implementation-dependent conversions may also occur.
The procedure Eopage is true iff a page marker has just been read, and
the corresponding space in now in the file buffer.
"Lazy lookahead" is used for all text files. This means that all
calls to Get are delayed until the buffer value is actually referenced,
either directly (using an uparrow) or through calls to Eoln, Eof, Eopage,
Read, or Readln. This solves the usual problems with interactive input
(e.g., the Get done by Reset at the beginning of a program can mean that
the user has to type in something before the program has a chance to print
out a prompt. A similar problem occurs with Readln, when the first
character of the next line would be read in prematurely.)
2.4 Extensions to Read and Write
- For all field widths (if there are two field-width-type
parameters, the first one only), a negative value will
mean that the value written will be left-aligned
instead of right-aligned. For string variables, if
Abs(Fieldwidth) < Length, then the last Length
- Abs(Fieldwidth) characters of the string will be
written.
- Variables of enumerated types may be read and written.
The field width is interpreted the same as for strings.
Enumerated constant names are uppercased when they are
read in.
- Sets of readable and writeable types may also be read
and written. They appear exactly as set constants
appear in Pascal programs. The field width is
interpreted for each element the same as it would be
for the set element type. For instance,
"Writeln ([1,3]:6") would be written as
[ 1, 3]
- Integers may be written in other bases beside base 10
by including an optional field-width-type parameter,
which may be anywhere from 1..16. The field width is
the same as for base 10. Integers may also be read
from a file in other than base 10, by including a
field-width-type parameter in the call to Read or
Readln.
- Real numbers may have a capital "E" as well as the
standard small "e" in the exponent part.
2.5 Filestrings
The conversion facilities of Read and Write may be used to read and
write to strings by using Filestrings. Although this is really a Pascal*
feature, a kludge has been put in to allow Filestrings in Upas. A
declaration of a Filestring looks as follows. The declaration can be in
any form, except the field names must be exactly as given. TEXT can be of
any size.
TYPE Filestring20 =
FILE OF RECORD
Pbuffer: Integer;
Maxlength,Length: Integer;
Text: Packed Array[1..20] of Char;
END;
A filestring is like a string, except that it may be used instead of a
file in calls to Eof, Get, Put, Read, and Write (but not Readln and
Writeln). It must be initialized by calling Strset or Strwrite. Strset
initializes a hidden field, Readpos, which is the current "file position".
It may be read using the standard procedure Curpos (see below).
Eof is true iff Readpos > Length. An error occurs if Readpos > Length
at the beginning of a call to Get or Read. An error also occurs if
writing to a filestring causes its Length to exceed its MaxLength.
Example of use:
VAR S: Filestring20;
{Initialize string for writing. Give its maximum length.}
StrWrite(S,20);
{Encode two integers.}
Write (S, I:3, ' ', J:3);
{Now S↑.Length = 7; Print out the string}
Write (Output, S↑.Text:S↑.Length);
{Initialize for reading.}
StrSet(S,20);
{Convert back to binary; Eof(S) becomes true.}
Read (S, I, J);
2.6 Random Access
Function Filesize (var Filevar: Anyfile): 0..Maxint
returns the current number of components in a file.
A file may be accessed randomly by using the procedure
Seek (F:Anyfile; N:1..Maxint)
This sets the file position to N. If the file is open for writing,
then the Nth component of the file will be overwritten by the next Write
or Put (if the length of the file is less than N-1, it is expanded to a
length of N first). If it is open for reading, then a Get is done and the
Nth record appears in the file buffer, subject to lazy lookahead.
(Currently not implemented -- you must do the Get yourself.)
2.7 Other Standard I/O Procedures
Function Curpos (var Filevar: Anyfile): 0..Maxint: Returns the
current file position. For files open for output or both input and
output, this is the number of the component currently in the file buffer.
For files open only for writing, this is the number of the component about
to be written, i.e., Filelength + 1;
Procedure Close (var Filevar: Anyfile): Closes file.
Function Filestatus (var Filevar: AnyFile; var Name:Vstring): 0..3:
Returns 0 if file closed, 1 if open for input, 2 if open for output, or 3
if open for both input and output. If file is open, returns the first
Name.Maxlength characters of the name in Name.
Procedure Filepos (var Filevar: Text; var Pagenum, Linenum, Charnum:
0..Maxint): Returns page, line number, and column number of the next
character that will be read from the file (must be open for input).
Does not work for random access.
3. Mark, Release, New, Dispose
There are two systems for dynamic storage allocation: one that uses
Dispose (*** not implemented ***), where individual records can be
de-allocated regardless of order of allocation, and one that uses Mark and
Release, where records are de-allocated in groups in a stack-like fashion.
(Note that this second method is non-standard and should be avoided
whenever possible).
Procedure Mark (Marker: ↑T), where T is any type, has the effect of
creating a marker which is then stamped on all items which are allocated
in the heap until the next call to Mark or Release. Release (Marker)
de-allocates all items that were allocated after the call to Mark which
created the marker.
Programs may have calls to any of the three procedures described. The
system that is actually used depends on which system is loaded with the
program. If the first system is loaded, calls to Mark and Release will
have no effect. If the second system is loaded, calls to Dispose will
have no effect.
4. Other Standard Procedures
Function Min (X,Y: T): T -- returns the minimum of two arguments,
which may be of any ordinal or real type.
Function Max (X,Y: T): T -- returns the maximum of two arguments.
*** Function Typeahead (VAR Filevar: Text): Boolean: On systems
with typeahead, returns TRUE if there is some input waiting.
*** Procedure SetInputMode (VAR Filevar: Text; B: Boolean):
Boolean: If Filevar is an interactive file, then user input will
be gotten a line at a time if B is true; otherwise it will be
gotten a character at a time.
*** Function Space: Integer: Returns the amount of space left in
the heap, in words.
Function Clock: Integer: Returns current system time, in
milliseconds.
Procedure Exit (Exitcode: Integer): Causes abnormal termaination of
a program. Passes a system-dependent exit code to the operating system.
Procedure Date (VAR Datestring: String(8)): Returns the current time
in the format 'HH:MM:SS'.
Procedure Time (VAR Timestring: String(8)): Returns the current time
in the format 'MM/DD/YY '.
Procedure Pdate (VAR Day,Month,Year: Integer): Returns the current
date in the form: Day: 1..31; Month: 1-12; Year, 1982..???;
Function Ptime: Integer: Returns the current time in 60ths of a
second past midnight.
6. Comments
Comment characters are "{" and "}", "%" and "\", and "(*" and "*)".
Contrary to the standard, "\", "}" and "*)" are not considered equivalent;
a matching comment character is always searched for. This allows nesting
of comments, which is useful when commenting out large blocks of code.
Note that a line that begins with a "{", possibly preceded by white
space, and ends with a "}" is treated specially by the version changer,
and so should be avoided (for instance, by adding extra white space at the
end of the line).
The use of "%" and "\" is strong discouraged, since it is non-standard.
7. System specs
Significant characters in identifiers: 16
Maximum characters in string constant 288
Maximum set size no limit
Minimum lower boundary for set -minint
Maximum elements in a set constant 1152
Maximum nexting of procedures and
WITH statements 20
Running the system at SAIL and S1-A using PAS
The U-code system is run on the S1-A by means of a program called Pas.
There is one Pas program for each target machine. Use "P2" for the Mark
IIa and "P10" for the Dec-10. (The generic name "PAS" is used in the
examples here.)
R PAS;PROG
will cause PROG.PAS or PROG.FOR to be compiled, loaded, and executed.
Note that very occasionally some parts of the compiler may be loaded
with the debugger. This means that you may have to type "END" at it when
you get the prompt ">>".
Also, you may occasionally get the message "?execution deleted" after
the loader has finished. In this case, type "S" to start the program
running.
The last PAS command can be re-executed by typing "R PAS". You can
edit the last command (using the WAITS line editor) by typing "R PAS;:".
FORMAT
------
A PAS command consists of "R PAS;", followed by at least one FILE
NAME, followed by any number of PAS SWITCHES and PROGRAM SWITCHES.
PAS SWITCHES are preceded by a "/". PROGRAM SWITCHES (i.e., the compiler
options described previously), may be passed through to the compiler by
preceding them with a "\" or "@". Examples:
R PAS;PROG.PAS\B-\D+
R PAS;PROG.FOR\BCHK-\DBUG+
These switches may be given directly to the programs even when not
using PAS. In this case, a regular slash should be used:
RU UPAS10[DMP,PN]
UPAS> PROG/B-/D+
You can add a switch onto a previous PAS command by simply omitting the
file name:
R PAS;\B-
MULTIPLE MODULES
----------------
PAS can only handle one module at a time. To compile and load two modules,
MODULE1.PAS and MAINPROG.PAS on the Dec-10 you would type:
R P10;MODULE1/REL
R P10;MAINPROG/REL
EXE MAINPROG,MODULE1
FILE NAMES
----------
In general, a PAS command specifies a source file and a destination file
(which may then be executed) and PAS figures out how to perform the
transformation. For instance, if you wanted to compile a file only to
FAIL assembly language and then look at the result, you would type
R P10;PROG.FAI←PROG.PAS/E
or
R P10;PROG/FAI/E
A file name is of the form FNAME.EXT[PRJ,PRG], where anything except
FNAME is optional. Either part of the [PRJ,PRG] may be left off, e.g.
"TRIAL.FOR[FOR,". EXT may be any one of the following: PAS, FOR, BCO,
ZCO, ICO, FAI, S1, or LDI. If you leave out EXT, PAS will try out the
extensions in the order given until it finds a file. A source file,
destination file, or both can be specified:
<source file>
<destination file> ←
<destination file> ← <source file>
A destination file can be used to specify that you want the final file
and all temporary files, such as FNAME.UCO and FNAME.LDI to have a
different name or be written to a different area. The default area is
your current area, (not [PRJ,PRG]).
PAS SWITCHES
--------
/E edit the destination file
/R edit the destination file, readonly
/D (Dec-10) if destination file is REL: load RAID
optimize:
/O1 using only procedure merger
/O2 using only global optimizer
/O using both
/FOR use Fortran run-times (MarkIIa only, when starting from UCO,
S1, or LDI file -- usually the Pascal runtimes are loaded
by default)
/DDT also load DDT.LDI (MarkIIa only, when program is to be transferred
to bare machine)
/Cn increases core to n when running translator programs;
default is 200. Use this when you get a "Not enough memory for
stack" error.
/UCO translate the B-code file to U-code
/BCO,/S1,/FAI,/REL,LDI go only to this point in the translation process
(equivalent to having a destination file with the same extension)
/SAV Dec10 only: save core image after loading
/S Single step; do one phase of translation only.
/XX (used for debugging PAS)